Using HomeSite
Chapter 2  Exploring the Workspace

Getting the Most from the Help System

The online Help system encompasses a variety of features:

• Pop-up Help for basic tag syntax (F2)
• Comprehensive context-sensitive tag Help (F1)
• Embedded Help in dialog boxes and tag editors
• An extensive collection of searchable references in the Help tab

Opening dialog box Help

Help text in tag editors and in the Tag Chooser provides context-sensitive syntax and usage information.

To view Help text in a tag editor or in Tag Chooser:

1. Click the Toggle Embedded Help button (Alt+H) to see Help text in a pane at the bottom of the dialog box.
2. Click the Show help in separate window button (Alt+M) to view the Help text in a floatable browser window.

Creating Help files for custom tag editors

Using the Allaire Visual Tools Markup Language (VTML), you can edit Help text in dialog boxes or add your own. See Customizing the Development Environment for details.

Accessing Help References

The Help system is an extensible resource for learning about product features, technology extensions, and other development topics. The online Help References contain the printed product documentation in HTML format and additional online references.

Click the Help tab at the bottom of the Resources window to view the Help References tree. The Help toolbar is located at the top of the Help References window.

Printing Help topics

If you are using Internet Explorer as the internal browser, you can print a Help topic by right-clicking the document in Browse mode and selecting Print. The default internal browser does not support printing.

Bookmarking Help topics

You can get quick access to Help documents by bookmarking them. Bookmarks can be assigned to documents in the Help tree and to HTML documents in the file system or on the Internet.

To bookmark a document in the Help Tree, right-click the document title and select the Add bookmark command. If the Help document is open, it displays automatically in the Bookmarks list. If the document is not open, you need to right-click again and select the Refresh command.

To open a bookmarked Help document, click the down arrow next to the Bookmarks icon on the Help tab toolbar and select from the list.

You can maintain bookmarks by selecting Organize Bookmarks from the Help Bookmarks drop-down list.

To bookmark an external document:

1. Click the Bookmark button in the Help toolbar to open the Help Bookmarks dialog box.
2. Click the Add button to open the Add Bookmark dialog box.
3. Enter a name for the bookmark.
4. Enter a URL or a filepath for an HTML document.
5. Click OK to add the bookmark to the Help Bookmarks list.

Searching Help References

You can do everything from a simple title search to advanced searches using complex criteria.

To run a search:

1. Click the Search button on the Help toolbar to open the Search Help References dialog box.

   The first time you open the search dialog box, you will be prompted to index the Help References. Allaire recommends doing this, as it greatly improves search engine performance. After the initial indexing, it checks the Help References tree for changes each time you open the Help panel and automatically indexes the documents again if needed.

2. Enter a word or phrase in the Enter the word(s) to find box.

   For information on using search operators, click the Search Tips button.

3. To limit the references searched, select the Search only in selected references option and select the check box next to one or more references.
4. Click the Search button.

   The Help References pane shows the search results.

5. Double-click a document in the results list to open it.

The results list is saved until a new search is run, so you can return to the document list by clicking the Search results button on the Help toolbar.

Using advanced search operators

You can use a variety of advanced search operators to make your searching more precise. For information on using advanced search operators, click the Search Tips button in the Search Help References dialog box.

A printable copy of the Search Tips, titled search_tips.pdf<, is installed >in the Help/Allaire Support folder of your installation directory. If you have Adobe Acrobat Reader on your system, you can open this file by double-clicking it in Windows Explorer.

Indexing the Help files

The Verity search engine checks the Help folder contents and revises the index when files are added or deleted.

If you have problems with the Help Search operation, Allaire recommends that you re-index the contents of the Help folder. To do this, close the program, delete the /Verity/Collections folder, start the program, and run a search.

Extending the Help system

One of the Help system's most useful features is its extensibility. You can add documents to the Help system by dragging and dropping them into the Help folder, either from the Files tab or Windows Explorer.

Help document files are generally in HTML, but you can include text files. The Help browser will use the file name as the title. You can also create hyperlinks from within an HTML file to files with txt, dtd, and pdf extensions if you use Internet Explorer as the internal browser. Web graphics files (GIF, JPG, PNG) are viewable in Help files.

This extensibility gives you a number of opportunities:

• You can write and install your own custom Help files.
• You can download documents from the Web and add them to the Help system.
• You can edit existing Help topics.
• You can distribute Help files; this can be particularly helpful for team development.

To create a new folder in the Help tree:

1. Open the Files panel in the Resources window.
2. Navigate to the Help folder of your installation.
3. Right-click in the files pane and select the Create Folder menu item to open a new folder box in the directory pane.
4. Type a folder name in the box and press Enter to save the new folder.

   You might need to press F5 to refresh the Help display.

You have several options for adding documents to the Help system:

To add documents to the Help tree do one of the following:

• Write an HTML Help file and save it to a folder in the Help directory.
• Use standard Windows commands to paste a file into a Help folder.
• Select File > Open from the Web to open an HTML document, then save it to a folder in the Help tree.

Adding Help References to the booktree structure

If you add a folder to the Help directory, the folder appears at the bottom of the Help References list. For most users, this is all you need.

If, however, you want to control the display order of the Help References, you can edit the booktree.xml file in the Help root directory. The booktree structure uses a simple tag set to configure the Help display on the book, chapter, and page level. A quick study of the file will get you started.

The parser reads the booktree tags from top to bottom, so you can just insert folder and file tags where you want the references to appear in the Help list. This applies to rearranging existing Help content and to adding new files. Alternately, you can use the path attribute in the book and chapter tags to specify the folder location.

To add a folder to the Help structure:

1. Copy the new folder into the Help root directory.
2. Open the Help directory from the Files tab.
3. Make a backup copy of the booktree.xml file.
4. Open the booktree.xml file in the Editor.
5. Enter a book tag for the new folder.

   Example: <help_book path="folder name">Custom Help Files.

The new folder now appears in the order you set up, but the files in the folder will be displayed in alphabetical order. If you want to control the display at the chapter and page level, you can tag these entries in the booktree file.

Displaying text files in the Help structure

Text files can be added to the Help tree. The Help browser default file type is HTML, so it looks for a TITLE tag in each file. If it doesn't find one or the tag is empty, it uses the filename in the Help tree display. You can use the <help_page title=""> attribute to add title text, if you wish.

Adding media content

You have considerable flexibility in adding supporting files (such as graphics, animations, video, and sound) to Help documents. One approach is to create a file structure in the Help tree that conforms to the media file references in your documents. Alternately, you can supply a URL or accessible file location for remote files.

Be aware that if you are using the default internal browser or an older external browser, proper playback of media files is limited.

Copyright © 2000, Allaire Corporation. All rights reserved.